home *** CD-ROM | disk | FTP | other *** search
/ Info-Mac 4 / Info_Mac IV CD-ROM (Pacific HiTech Inc.)(August 1994).iso / Newton / Utilities / Slurpee-10 Folder / Slurpee.txt < prev    next >
Text File  |  1994-06-04  |  10KB  |  251 lines
  1. Slurpee.txt
  2. 6/6/94
  3.  
  4. Slurpee 1.0
  5. transfers paragraphs or tab-delimited text
  6. between a text file and Newton soup entries
  7. via a terminal emulator and serial connection
  8.  
  9. Keywords: data and text transfer, soup utility, terminal emulator, freeware
  10.  
  11.  
  12. =====
  13. Why?
  14.  
  15. I wanted a convenient way to move information from the desktop to soups on the
  16. Newton, especially text paragraphs to separate Notepad entries, and vice
  17. versa.  Newton Connection Kit (NCK) is also a possibility, though it is
  18. slower, more complicated, and expensive.  Although Slurpee was created
  19. primarily to support moving NewtonScript application/method sources by users
  20. of my Newt application development tool, I thought that this utility may be
  21. useful for others as well.
  22.  
  23.  
  24. =====
  25. Slurp and Slurpee -- Introduction and Differences
  26.  
  27. Slurpee is a customized version of the Apple DTS "Slurp-3" example -- with
  28. thanks to the original author Scott (Zz) Zimmerman. The original Slurp
  29. documentation and examples are included as SlurpOld.txt and CasioNam.tab. I
  30. did not include the Slurp NTK project source files -- these can be obtained
  31. from AppleLink and ftp.apple.com.
  32.  
  33. Slurp: Copyright 1993, 1994, Apple Computer, All Rights Reserved.
  34. Slurpee modifications: Copyright 1994, S. Weyer
  35.  
  36. Slurpee is freeware (especially since so much of it is based on Slurp). Slurpee
  37. may be freely distributed via online services and bulletin boards if it is
  38. unmodified and includes this and other files mentioned here.  It may not be
  39. commercially bundled or redistributed on CD-ROM, floppy disk, PCMCIA, networks
  40. or other media without permission.
  41.  
  42. With enough encouragement, I may fix problems and add additional features. Of
  43. course, you can also start with the original Slurp and roll your own version.
  44. If Slurpee is useful to you, you can send email or a postcard, or better yet,
  45. you can express your appreciation by registering for "Newt". Newt is a
  46. shareware native Newton application development environment, i.e., you can
  47. build applications in NewtonScript on your Newton.  More info at end of this
  48. file.
  49.  
  50. The original Slurp is one-way: it transmits lines in a desktop tab-delimited
  51. text file sent over a serial connection into Newton soup entries. Slurpee is
  52. two-way: it can also send Newton soup entries as a tab-delimited text file.
  53. (This combines functionality you'd find in the DTS SerialPro example and the
  54. freeware Pour utility).  Slurpee also works both ways in converting between
  55. multiline text paragraphs and entries in the Notes soup.  I think I've fixed a
  56. few Slurp problems with disconnecting cleanly.  I also added a "para" datatype
  57. that's useful for adding a note to a Names entry.
  58.  
  59. The original minimalist Slurp interface has changed only in the title, and some
  60. additional status messages.  What's transferred and in which format is
  61. controlled on the desktop side. For example, to send data to your Newton, you
  62. tell Slurpee to Receive, and then send text containing soup name, format
  63. specification, and data, via your terminal emulator, usually as a file.  To
  64. send data from your Newton, you also set Slurpee to Receive; however, the text
  65. file you send contains a soup name and format specification, but no data --
  66. just a Dump command (this assumes you set up a log file to capture the data
  67. returned).  Directions on how to setup Slurp/Slurpee with a terminal emulator
  68. can be found in the original SlurpOld.txt and later in this file.
  69.  
  70. Warning: since Slurpee can add or remove entries from your soups, please keep
  71. your information backed up, and follow the formats and commands carefully.
  72.  
  73. =====
  74. Slurpee Uses
  75.  
  76. Here is a summary of the four kinds of transfer supported by Slurpee:
  77.       direction                         soup
  78. ----------------------      -------------------------
  79. from desktop to Newton      1. any soup      2. Notes
  80. from Newton to desktop      3. any soup      4. Notes
  81.  
  82. =====
  83. 1. the original Slurp ("Slurp classic")
  84. first line    soup name, e.g., Names
  85. second line   frame specification, e.g., see SlurpOld.txt and CasioNam.tab 
  86. other lines   each tab-delimited line corresponds to an entry
  87. last line     BYE!
  88.  
  89. note: this only works with existing soups. Slurp/Slurpee does not create new
  90. soups (currently).
  91.  
  92. For Names, I've found that a phones field is required, otherwise the entries
  93. will generate errors later when you browse them.  At a minimum, you need
  94. something like phones: ["workPhone"] in your framespec, then an extra tab in
  95. your data entries to reflect an empty field.
  96.  
  97. If you'd like to add a text note to a Names entry (the text field you see when
  98. you Show:Card&Notes), include notes: ["para"] in the frame spec. In the data
  99. entries, the text in this position up to the next tab (or end of line if it's
  100. last) will be included as a single paragraph in the note field.
  101.  
  102. =====
  103. 2. Slurp for Notes
  104. first line    Notes
  105. second line   frame specification, e.g., {labels: 'Business}**
  106. line1 text
  107. line2 more text
  108. -----         paragraph delimiter (at least 5 dashes)
  109. more lines
  110. -----
  111. BYE!
  112.  
  113. **the frame specification in 1) is more of a template with type information;
  114. for Notes, it is used to provide default values.  Currently, only labels is
  115. supported: the value is a symbol corresponding to a folder destination, e.g.,
  116. 'Personal, 'Business, or nil (for Unfiled).  In the future, other slots might
  117. be supported like font, etc.  e.g., see Business.txt
  118.  
  119. Note: if you include a value for labels slot that does not (yet) exist, be sure
  120. to do Edit Folders later on your Newton to add it -- otherwise, the only
  121. way you'll see these entries is via All Notes.
  122.  
  123. Erase command:  if you know what you are doing (and have backed things up
  124. first), you can insert an ERASE! command as the third line for 1&2.  This
  125. erases all entries from the specified soup, or if you've specified labels in
  126. your frame spec (for Names or Notes), it erases just the entries in that
  127. folder.  This can be handy especially if want to get rid of many existing
  128. entries before adding new information.  Warning: this does not give you a
  129. dialog box asking to Confirm erasing of entries!!!  For example, if you edited
  130. Newt sources for your project on the desktop, and wanted to replace these
  131. completely on your Newton, you could do something like:
  132.  
  133. Notes
  134. {labels: 'Programming}
  135. ERASE!
  136. createApp
  137. func()
  138. ...
  139. -----
  140. addFields
  141. func()
  142. ....
  143. -----
  144. BYE!
  145.  
  146.  
  147. =====
  148. 3. Slurp in reverse
  149. first line    soup name, e.g., Names
  150. second line   frame specification, e.g., CasioNam.dmp
  151. DUMP!
  152.  
  153. same powerful frame specification as in 1). entries are written to terminal
  154. emulator as tab-delimited lines in frame specification order.  after the Dump
  155. command is encountered, Slurpee pauses 10 seconds before transmitting data so
  156. that you have a little bit of time to set up a log/capture file.  Any data
  157. fields with text values that contain newlines will be transmitted as is (you
  158. may need to re-edit results into a true tab-delimited text format).
  159.  
  160. =====
  161. 4. Slurp for Notes, in reverse
  162. first line    Notes
  163. second line   frame specification, e.g., {labels: 'Business}**
  164. DUMP!
  165.  
  166. **this is used as a filter to copy entries from only that folder. it copies
  167. just the first data entry from each Note (if it is non-empty text) as a
  168. paragraph. for example, see Business.dmp
  169. entries are written as multi-line entries separated by -----
  170. same 10 second pause before transmitting
  171.  
  172.  
  173. =====
  174. How to Use (see SlurpOld.txt for further info):
  175.  
  176. - Download Slurpee to your Newton.
  177.  
  178. - Serial cable (still) connected to the Newton, with no other open serial
  179.   connections on the desktop side (e.g., NTK inspector), or any other
  180.   current use of comms on the Newton (e.g., beaming).
  181.  
  182. - Open a communications program (e.g., terminal emulator) on your desktop
  183.   system, with the following specs:
  184.     Serial Tool, 9600 baud, 8 data bits, 1 stop bit, XON/XOFF handshaking
  185.  
  186.   - For file transfer, specify the Text Tool.
  187.  
  188. - Open Slurpee and tap the "Receive..." button.  
  189.  
  190. - On the Mac/PC, choose "Send File..." in the comm program, and choose the
  191.   file to be sent.  If you are doing a "Dump", immediately setup a file to
  192.   log/receive/capture the result.  Slurpee will display the number of entries
  193.   received/dumped in a view near the top of the screen.  When the file
  194.   transfer is complete, Slurpee will automatically disconnect.
  195.  
  196.  
  197. =====
  198. Slurpee Change History
  199.  
  200. 1.0
  201. -----
  202. - initial public release
  203. - added 10 second delay after a DUMP! to allow time to log/receive/capture a file
  204. - added an ERASE! command to clear out all soup entries or just those in a folder
  205. - added a "para" datatype (useful for adding a note to a Names card)
  206. - disconnects more cleanly
  207.  
  208. 0.1
  209. -----
  210. - alpha/beta releases to Newt users
  211.  
  212.  
  213. =====
  214. Author
  215.  
  216. Stephen Weyer
  217. 17 Timber Knoll Drive
  218. Washington Crossing, PA 18977-1052
  219. Internet: weyer@guest.apple.com
  220. America Online/eWorld/NewtonMail: SteveWeyer
  221. AppleLink: WEYER.S
  222.  
  223.  
  224. =====
  225. Info about Newt
  226.  
  227. Newt 2.2 (aka Newt Turtle):
  228. a native environment for developing simple applications using NewtonScript,
  229. and for creating graphics using gestures, buttons, and NS.
  230.  
  231. Keywords: object-oriented programming, application development environment,
  232. NewtonScript, NTK, learning, graphics, mathematics, Logo.
  233.  
  234. newt-devenv-22.sit / .hqx is usually found on:
  235.   internet: newton.uiowa.edu:pub/newton/software/app/
  236.             sumex-aim.stanford.edu(&mirror sites):info-mac/newton/app/
  237.   newsgroups: comp.binaries.newton
  238.   America Online(AOL): PDA:New Files (or PDA:Software Libraries:Newton)
  239.   Compuserve: GO NEWTON (DL 8)
  240.   AppleLink: Newton:Newton User Discussions:Freeware, Shareware and Demos
  241.   eWorld: ???
  242.   
  243. Newt is shareware ($30 before 8/1/94) -- registered users receive a manual
  244. describing additional features and NewtonScript syntax, along with source
  245. examples -- of particular interest may be the Slurpee application itself in
  246. Slurpee format for Newt. See NewtNews.txt for further info.
  247.  
  248. Also see RUNewt (aka Run,Newt,Run) -- an application for running, beaming and
  249. mailing applications created by Newt 2.2. [runewt-22.sit / .hqx]
  250.  
  251.